home *** CD-ROM | disk | FTP | other *** search
/ PC World 2008 September / PCWorld_2008-09_cd.bin / v cisle / sadanastroju / delicious_bookmarks-2.0.64-fx.xpi / chrome / deliciousBookmarks.jar / content / bookmarks.js < prev    next >
Encoding:
Text File  |  2008-06-19  |  9.0 KB  |  181 lines
  1. /*
  2.  * Author: Yogish Baliga
  3.  * Company: Yahoo! Inc. 
  4.  * Date: 23rd August, 2006
  5.  *
  6.  * All bookmarks are stored in bookmarks.rdf file located in the profile directory. Inverse index of
  7.  * tags to bookmark resource is also stored in bookmarks.rdf. 
  8.  *
  9.  * NC:YBookmarksRoot is the container for all the bookmarks in the system.
  10.  * NC:YBookmarksTagRoot is the container for all the tags in the system.
  11.  * 
  12.  * Elements within NC:YBookmarksRoot are the resource references. Each reference point to the individual
  13.  * bookmarks. Each bookmark resource has outgoing arcs.
  14.  *       NC:Name          - nsIRDFLiteral
  15.  *       NC:URL           - nsIRDFResource
  16.  *       NC:Description   - nsIRDFLiteral 
  17.  *       NC:LastCharset   - nsIRDFLiteral 
  18.  *       NC:tag           - nsIRDFLiteral (multiple)
  19.  * 
  20.  * Elements within NC:YBookmarksTagRoot are the resource refrences. Each refrence point to the container.
  21.  * These container has 1 outgoing arc and references to the bookmark resources.
  22.  * 
  23.  *      Outgoing arc is http://www.mozilla.org/bookmark#tagvalue. The target of this relation is the 
  24.  *      actual tag value (nsIRDFLiteral).
  25.  *
  26.  *       ----------------------
  27.  *  --->| NC:YBookmarksTopRoot |
  28.  * |     ----------------------
  29.  * |
  30.  * |       -------------------     contains             ----------------------
  31.  * |------| NC:YBookmarksRoot |----------------------->| bookmark resource    |  contains
  32.  * |       -------------------                         | (Anonymous resource) |<---------------
  33.  * |                                                    ----------------------                 |
  34.  * |                                                                                           |
  35.  * |                                                                                           |
  36.  * |       ----------------------    contains    ----------------------   contains     ----------------------
  37.  *  ------| NC:YBookmarksTagRoot |------------->| Tag Sequence         |------------->| Tag resource         |
  38.  *         ----------------------               | (Anonymous resource) |              | (Anonymous resource) |
  39.  *                                               ----------------------                ----------------------
  40.  * 
  41.  *
  42.  * NC:YBookmarksRoot has the following outgoing arcs:
  43.  *
  44.  *    * http://www.w3.org/1999/02/22-rdf-syntax-ns#type     => http://home.netscape.com/NC-rdf#Folder
  45.  *    * http://home.netscape.com/NC-rdf#LastUpdateDate      => nsIRDFLiteral ( set to the string provided by the service provider.
  46.  *                                                                             This can be used for incremental updates
  47.  *                                                                           )
  48.  * 
  49.  * Following are the Arcs out of bookmark resource
  50.  *  
  51.  *  * http://home.netscape.com/NC-rdf#URL                 - nsIRDFResource
  52.  *  * http://home.netscape.com/NC-rdf#Name                - nsIRDFLiteral
  53.  *  * http://home.netscape.com/NC-rdf#Description         - nsIRDFLiteral
  54.  *  * http://home.netscape.com/NC-rdf#LastCharset         - nsIRDFLiteral
  55.  *  * http://home.netscape.com/NC-rdf#WebPanel            - nsIRDFLiteral
  56.  *  * http://home.netscape.com/NC-rdf#BookmarkAddDate     - nsIRDFDate
  57.  *  * http://home.netscape.com/NC-rdf#LastVisitDate       - nsIRDFDate
  58.  *  * http://home.netscape.com/NC-rdf#LastModifiedDate    - nsIRDFDate
  59.  *  * http://home.netscape.com/NC-rdf#VisitCount          - nsIRDFInt
  60.  *
  61.  *  * http://www.mozilla.org/bookmark#tag ( There are multiple arcs of this resource )
  62.  * 
  63.  * Tag Sequence is having the following attribute
  64.  *  * http://www.mozilla.org/bookmark#tagvalue            - nsIRDFLiteral
  65.  *  * http://home.netscape.com/NC-rdf#ChildCount          - nsIRDFInt
  66.  * 
  67. */
  68.  
  69. /*
  70.  * All functionality is moved to singleton object. Here is how to obtain the ybookmarks service object.
  71.  * 
  72.  *  var bookmarksService = Components.classes["@mozilla.org/ybookmarks-service;1"].
  73.  *                                       getService( Components.interfaces.nsIYBookmarkService );
  74.  *
  75.  * See components/nsIYBookmarksService.idl for the methods exposed by nsIYBookmarksService interface.
  76.  *
  77.  * Q. How to add bookmark
  78.  * A.
  79.  *      var tags = [ "Hello", "World" ];
  80.  *      bookmarksService.addBookmark( "http://www.yahoo.com", "Yahoo!", "charset string", false, "Some Description", tags.length, tags );
  81.  *
  82.  * Q. How to get all tags
  83.  * A. 
  84.  *      var allTags = bookmarksService.getTags(null, {} );
  85.  *     
  86.  *     Note: 2nd parameter is necessary here because of some XPCOM limitations.
  87.  *   
  88.  *     for ( var counter = 0; counter < allTags.length; ++counter) {
  89.  *       yDebug.print( "Tag => " + allTags[counter] );
  90.  *     }
  91.  *
  92.  * Q. How to get tags for a given URL?
  93.  * A.
  94.  *      var tags = bookmarksService.getTags( "http://www.yahoo.com", {} );
  95.  * 
  96.  *    See the previous answer for how to loop through the tags.
  97.  * 
  98.  * Q. How to get bookmarks for a given tag.
  99.  * A.
  100.  *     var bookmarks = bookmarksService.getBookmarks( "tag", {} ); 
  101.  * 
  102.  *    bookmarks is an array of instance of nsIYBookmark. 
  103.  *  Following are the members of the instance:
  104.  *    name        => Title of bookmark
  105.  *    url         => URL of bookmark
  106.  *    description => Description of bookmark
  107.  *    charset     => Charset of the web page
  108.  *    tags        => An instance of nsIArray. Each element of this array is nsISupportsString
  109.  *                   This is because of the limitation of IDL in XPCOM.
  110.  
  111.  *    In Javascript it can be accessed as
  112.  *
  113.  *    for ( var counter = 0; counter < bookmarks.length; ++counter ) {
  114.  *      var book = bookmarks[counter];
  115.  *      yDebug.print ( "Title => " + book.name );
  116.  *      yDebug.print ( "URL => " + book.url );
  117.  *      yDebug.print ( "Description => " + book.description );
  118.  *      yDebug.print ( "Charset => " + book.charset );
  119.  *    
  120.  *      // Tags is somewhat trikcy.
  121.  *      var tags = book.tags.enumerate();
  122.  *      while ( tags.hasMoreElements() ) {
  123.  *        var tag = tags.getNext().QueryInterface( Components.interfaces.nsISupportsString).data;
  124.           yDebug.print ( "Tag => " + tag );
  125.  *      }
  126.  *    }
  127.  *
  128.  * Q. How to add custom keys to bookmark?
  129.  * A. Use get and set methods as in nsIYBookmarkService.idl file.
  130.  *    Following methods are provided:
  131.  * 
  132.  *       * setBookmarkKeyAsString ( url, key, value )
  133.  *       * setBookmarkKeyAsInt ( url, key, value )
  134.  *       * setBookmarkKeyAsDate ( url, key, value )
  135.  *
  136.  * Bulk set methods: (number of elements in keys and values must be equal to or greater than totalkeys. 
  137.  *                    Only totalkeys key-value pair are added to the bookmark. Rest are ignored.
  138.  *                    nth element in keys is set to nth element in values.
  139.                      )
  140.  * 
  141.  *       * setBookmarkKeysAsString ( url, totalkeys, keys, values )
  142.  *       * setBookmarkKeysAsInt ( url, totalkeys, keys, values )
  143.  *       * setBookmarkKeysAsDate ( url, totalkeys, keys, values )
  144.  * 
  145.  * Following are the get methods: These methods return an array. Each element in the output array corresponds to the 
  146.  *                                value of key in the rdf. The element in the output array will have null if 
  147.  *                                correponding key is not in the rdf. Date and Int values are set to 0 if key are not
  148.  *                                found in the rdf.
  149.  * 
  150.  *       * getBookmarkStringValues( url, totalkeys, keys, totalvalues )
  151.  *       * getBookmarkIntValues( url, totalkeys, keys, totalvalues )
  152.  *       * getBookmarkDateValues( url, totalkeys, keys, totalvalues )
  153.  * 
  154.  * Example:
  155.  *
  156.  *    bookmarksService.setBookmarkKeyAsString( "http://www.yahoo.com", "hash", "asdasdlaksdoqwieqwe" );
  157.  *    bookmarksService.setBookmarkKeyAsInt( "http://www.yahoo.com", "id",  10 );
  158.  *    bookmarksService.setBookmarkKeyAsDate( "http://www.yahoo.com", "dt",  (new Date()).getTime() );
  159.  *  
  160.  *    bookmarksService.setBookmarkKeysAsString( "http://www.yahoo.com", 1, [ "hash" ], [ "lkjaoiwqeojqwoiejqowe" ] );
  161.  *    bookmarksService.setBookmarkKeysAsInt( "http://www.yahoo.com", 1, [ "id" ], [ 11 ] );
  162.  *    bookmarksService.setBookmarkKeysAsDate( "http://www.yahoo.com", 1, [ "dt" ], [ (new Date()).getTime() ] );
  163.  * 
  164.  * Example to fetch the keys: (out.value is set to number of elements in the output array. The last parameter is required,
  165.  *                             even though not used)
  166.  *
  167.  *    var out = {};
  168.  *    var hashes = bookmarksService.getBookmarkStringValues( "http://www.yahoo.com", 1, ["hash" ], out );
  169.  *    var ids = bookmarksService.getBookmarkIntValues( "http://www.yahoo.com", 1, ["id" ], out );
  170.  *    var dts = bookmarksService.getBookmarkIntValues( "http://www.yahoo.com", 1, ["dt" ], out );
  171.  *
  172.  * 
  173.  * Q. How to set and get the last update time for the incremental updates from the service provider?
  174.  * A. Use setLastUpdateTime and getLastUpdateTime methods.
  175.  *
  176.  *    Example:
  177.  *          bookmarksService.setLastUpdateTime( "time string from service provider" );
  178.  *          var lastUpdateTime = bookmarksService.getLastUpdateTime();
  179. */
  180.  
  181.